Release 10.1A: OpenEdge Development:
Progress Dynamics Administration

DCU driver files

The configuration file specifies another file, the DCU driver file. That file contains the information needed to set up the DCU’s wizard interface. You cannot use more than one DCU driver file during a DCU session.

Examine the default DCU driver file, setup1000B.xml. To customize the DCU for your own deployments, you can use the existing file as a template to add your own messages and other data. The beginning of the file contains basic information including messages and system information that will be useful gathering information during setup, as shown in the following example:

setup1000B.xml

<?xml version="1.0" encoding="UTF-8"?> <Setups>   <setup SetupType="ProgressSetup">     <ImageLowRes>install/img/imglores.bmp</ImageLowRes>     <ImageHiRes>install/img/imghires.bmp</ImageHiRes>     <IconFile>install/img/icfdcu.ico</IconFile>     <StartPage>Welcome</StartPage>     <SkipButtons>Close,Cancel,Quit,Finish,Check</SkipButtons>     <VersionNo>10.0B1P</VersionNo> ...   <message>     <MessageCode>MSG_blank_path</MessageCode>     <MessageDesc>The %1 path may not be left blank.</MessageDesc>   </message> ...   <registrykey>     <KeyName>reg_install_path</KeyName>     <KeyValue>::Startup:DLC</KeyValue>     <ExpandTokens>YES</ExpandTokens>   </registrykey> ...   <path>     <PathName>path_progress</PathName>     <PathValue>#\\Startup\DLC#</PathValue>     <ExpandTokens>YES</ExpandTokens>   </path>

The <registrykey> nodes point the DCU to the Windows Registry for needed information. As shown by the <path> node, the information can then be used to derive other needed values. The Configuration File Manager parses the XML in a single pass. Therefore, the order of the nodes is important. The parser cannot expand a token if a node uses that token before the node that supplies the data is parsed.

Page nodes

The DCU driver file also contains the description of each page that the DCU displays and defines the actions that can occur on those pages. The following excerpt describes the DCU’s Installation Paths page:

Page example from setup1000B.xml

<page Name="GetInstallPaths">   <Title>Installation Paths</Title>   <Group>Path</Group>   <Proc>install/obj/inpath.w</Proc>   <control>     <Type>Editor</Type>     <Name>edComment</Name>     <DefaultValue>For this utility to set up the environment, it needs to know the installation path that you chose during the first part of the installation. It has attempted to derive the path from the install. As the upgrade takes place, a log file will be written that contains details of what occurred during the upgrade. Please confirm that the Progress Dynamics Installation Path and Log File Name below is correct.</DefaultValue>   </control>

Note that the page is named and belongs to a named group. All the pages that cover a certain task should belong to the same group. The DCU uses the page name to target the correct page when an action is invoked. Because the pages are called by name, their nodes do not need to be listed in any order. This flexibility makes it easier for you to reuse individual pages in different sequences for different setup types. The <Proc> node gives the filename for the page. Each DCU page is created from the template, src/install/intmplframe.w.

Action nodes

Each <control> node describes an object on the page and how it behaves. The previous excerpt shows the description of the editor that appears in the page frame. The following excerpt shows the description of a Cancel button:

Cancel button from setup1000B.xml

<control>   <Type>Button</Type>   <Panel>Yes</Panel>   <Label>&amp;Cancel</Label>   <Name>Quit</Name>   <Justify>Right</Justify>   <action>     <Event>CHOOSE</Event>     <Action>QUIT</Action>   </action> </control>

The <action> node describes how a control reacts to one of the standard Progress 4GL events, which is listed in the <Event> subnode. The <Action> subnode can only contain a single character string, the name of the API that is launched by the event. The DCU assumes that the API is in the Install UI Manager by default. If you want to run an API from another manager, you can specify the manager using an <ActionTarget> node. The value in <ActionTarget> must match the named assigned to the manager in the <cManagerName> node in the DCU configuration file.

The DCU recognizes two special keywords in addition to any APIs in the managers: QUIT and FINISH. QUIT ends the DCU session without completing the upgrade. FINISH ends the DCU and signals that the upgrade completed successfully. The difference is important for release versioning.

While most actions are linked to events for specific controls, you can also attach actions directly to a page. The following excerpt shows an event linked directly to the GetICFDBParams page:

Action linked to a page from setup1000B.xml

<page Name="GetICFDBParams">   <Title>ICFDB Parameters</Title>   <Group>ICFDB</Group>   <Proc>install/obj/indbconn.w</Proc>   <action>     <Event>INITIALIZE</Event>     <Action>checkForDB</Action>     <ActionParam>ICFDB</ActionParam>   </action>

Action parameters

The following excerpt shows the description for the Back button on the Installation Paths page, and its two actions are processed in the order in which they are listed:

Back button from setup1000B.xml

<control>   <Type>Button</Type>   <Panel>Yes</Panel>   <Label>&amp;Back</Label>   <Name>Back</Name>   <Justify>Right</Justify>   <action>     <Event>CHOOSE</Event>     <Action>restoreProperties</Action>   </action>   <action>     <Event>CHOOSE</Event>     <Action>gotoPage</Action>     <ActionParam>Welcome</ActionParam>   </action> </control>

The second action shows an example of passing a parameter. In this excerpt, it is the name of the page that the DCU will display when the Back button is chosen. An action can only take a single parameter, which must be a character string.

However, the DCU recognizes two special strings for passing conditional parameters. These strings allow you to embed IF...THEN...ELSE and CASE expressions in the XML. Table 5–3 lists the operators that you can use in the expressions.

Table 5–3: Operators for conditional expressions 

Operator	Symbol
AND	&&
OR	::
Equals	=
Greater than or equal	>=
Less than or equal	<=
Not equal	<>

An example of the syntax for an IF expression is shown in this excerpt from the GetICFDBParams page:

IF...THEN...ELSE conditional expression

<action>   <Event>CHOOSE</Event>   <Action>gotoPage</Action>   <ActionParam>?db_build_icfdb=YES;GetICFSiteData;GetICFDBPatches </ActionParam> </action>

The IF expression begins with a question mark (?) followed by the expression the DCU evaluates. Semicolons (;) separate the results. The value after the first semicolon is the THEN result, and the value after the second semicolon is the ELSE result. So, the expression above reads, “If the value of db_build_icfdb is YES, then go to the GetICFSiteData page, else go to the GetICFDBPatches page.”

Note: While you can create complex IF expressions using the available operators, you cannot nest IF expressions. The results must be single-character strings, as with normal parameters.

An example of the syntax for a CASE expression is shown below:

CASE conditional expression

<action>   <Event>CHOOSE</Event>   <Action>gotoPage</Action>   <ActionParam>:session_date_format:dmy|page1:mdy|page2:ymd|page3:default|pa ge9 </ActionParam> </action>

The CASE expression begins with a colon (:) and the name of the property to evaluate. Each result begins with a colon followed by a pipe (|) delimited value pair. The DCU uses the first value pair that matches the evaluated property in the list of results. So, the expression above reads, “Check the session_date_format property. If the value is dmy, go to page1. If the value is mdy, go to page2. If the value is ymd, go to page3. If none of the conditions are met, go to page9.”

Data capture nodes

The DCU captures data from its wizard interface with a screen scrape procedure. How the data is stored is controlled through the use of two nodes: <StoreTo> and <TableVariable>. The following excerpt shows a fill-in field description that employs both methods:

Fill-in field from setup1000B.xml

- <control>   <Name>fiPath2</Name>   <DefaultValue>#_start_in_directory#\dcu.log</DefaultValue>   <ExpandTokens>YES</ExpandTokens>   <StoreTo>path_log</StoreTo>   <Label>Log File</Label>   <TableVariable>LogFile</TableVariable>   </control>

Which method you use to capture the data depends on when you want to have the data available. The DCU stores the data from a <StoreTo> node in a session parameter. The parameter can be defined in either the Configuration File Manager or in the DCU driver file. The data is then available to the DCU while the user steps through the rest of the wizard pages. The DCU stores the data from a <TableVariable> node in a temp-table. The data in the temp-table is used after the DCU has finished collecting data and starts processing. As the example shows, you can store the data in both places if you need it both before and after the DCU begins processing.

Database nodes

The last section of the standard DCU driver file describes the databases to upgrade. Each database has its own node. The DCU works through the databases in the order they are listed here. A database node specifies the information needed to connect to the database and lists a set of XML files that contain descriptions of the upgrades and datasets to be applied to the database.

The following excerpt shows the contents of a database node:

Database example from setup1000B.xml

<database>   <DBName>ICFDB</DBName>   <VersionSeq>seq_icfdb_dbversion</VersionSeq>   <MinimumVersion>020021</MinimumVersion>   <ConnectParams>-1</ConnectParams>   <DBDir>#path_db#\icfdb\icfdb.db</DBDir>   <DBDump>#path_src#\#dynamics_rootname#\db\icf\dump</DBDump>   <patch PatchLevel="0" DBBuild="Yes" NodeURL="db/icf/dfd/icfdbbuild.xml"/>   <patch PatchLevel="020022" NodeURL="db/icf/dfd/icfdb020022adolist.xml"/>   <patch PatchLevel="020022" NodeURL="db/icf/dfd/icfdb020022patch.xml"/>   <patch PatchLevel="020023" NodeURL="db/icf/dfd/icfdb020023patch.xml"/>   <patch PatchLevel="020024" NodeURL="db/icf/dfd/icfdb020024patch.xml"/>   <patch PatchLevel="020025" NodeURL="db/icf/dfd/icfdb020025patch.xml"/>   <patch PatchLevel="020025" NodeURL="db/icf/dfd/icfdb020025adolist.xml"/>   <patch PatchLevel="020026" NodeURL="db/icf/dfd/icfdb020026patch.xml"/>   <patch PatchLevel="100001" NodeURL="db/icf/dfd/icfdb100001patch.xml"/>   <patch PatchLevel="100002" NodeURL="db/icf/dfd/icfdb100002patch.xml"/>   <patch PatchLevel="100002" NodeURL="db/icf/dfd/icfdb100002adolist.xml"/> </database>

This example shows the information for setting up the Repository. It is recommended that you use the same technique for tracking the database version for your application databases. To enable identification of the current version of a database, each database requires a sequence with a name in the following format:

seq_logicaldbname_DBVersion

Where logicaldbname is the logical database name for the database.

This sequence tracks the version of the database as a six-digit integer. The first two digits are the version. The next two digits are the revision level. The final two digits are the patch level.

The current value of the sequence is not used, but the DCU reads the sequence maximum value to determine the current database version. The DCU uses this value to decide which patches must be applied to the target database to complete the upgrade. When a database definition delta file is loaded, the database definition should update the sequence definition to its new maximum value. The <MinimumVersion> node contains the minimum version of the database on which a particular setup can run.

The remaining nodes list the patch levels to apply during this upgrade. The associated files detail all the patch programs and ADOs that are part of a particular deployment. Notice that they are listed in ascending order by patch levels. Your files should always be listed in this order. The DCU reads the files in the order they are listed to build the temp-table of patches.